<!DOCTYPE HTML>
<html>
<head>
<title>帯域幅/遅延 プラグイン API</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">ドキュメント一覧</a> | <a href="index.html">API</a></span>
<h1>帯域幅/遅延 プラグイン API</h1>
<p>
帯域幅プラグインはサーバーへのユーザーのネットワークコネクションの帯域幅と遅延を測定します。帯域幅 API は <code>BOOMR.plugins.BW</code> に内包されます。
</p>

<h2 id="config">Configuration</h2>
<p>
bandwidth プラグインの全ての設定は <code>BW</code> の名前空間の下に入ります。設定オブジェクトについては <a href="../howtos/howto-6.html">使用方法 #6 &mdash; boomerang の設定</a> をご覧ください。
</p>
<dl>
<dt>base_url</dt>
<dd>
<strong>[推奨]</strong>
初期値では、bandwidth プラグインは帯域幅測定用の画像を現在のページのディレクトリーの <code>images/</code> サブディレクトリーから見つけます。これはあなたのサイト上の全てのページで正しいとは限りません。画像があるディレクトリーのパスを <code>base_url</code> パラメーターで設定ができます。絶対 URL または相対 URL で指定ができます。相対パスの場合、JavaScript ファイルからではなく boomerang が読み込まれたページからの相対パスになることを覚えておいてください。
</dd>

<dt>cookie</dt>
<dd>
<strong>[オプション]</strong>
ユーザーのコネクションの帯域幅と遅延の測定結果を格納する Cookie の名前。初期値は <code>BA</code> です。詳細は <a href="howto-3.html">使用方法 #3</a> をご覧ください。Cookie を無視して開始時間を完全に WebTiming API に依存させるには、ここに <code>null</code> のような偽の値か空文字を指定します。
</dd>

<dt>cookie_exp</dt>
<dd>
<strong>[オプション]</strong>
秒で表した Cookie の有効期限。初期値は7日間です。これはユーザーの帯域幅テストを再度行うまでにどれくらい空けるかを記述します。IP アドレスをもとにその間は変更されません。ネットワークコネクションの帯域幅は通常は定期的に大きくは変わらないため、実際はこの設定を何も変更する必要はありません。<br>
もしあなたがレアルタイムストリーミングのようなことを行っている場合、帯域幅のテストは適切ではなく、Cookie に短い値を設定するのは正しい方法ではありません。
</dd>

<dt>timeout</dt>
<dd>
<strong>[オプション]</strong>
ミリ秒で表した帯域幅のテスト全体のタイムアウト値。初期値は15秒です。帯域幅のテストは長時間実行できるため、時々ネットワークエラーが発生し終了しないかもしれません。タイムアウトは強制的にテストを終了させます。これはハードリミットです。もしタイムアウトになると、テストの続行を停止してこの時点で取得できているデータから帯域幅を計算しようとします。タイムアウトを長くすればさらに多くのデータを取得し精度を向上できますが、長くした分、ユーザーがページを離れる前にテストが終了しないリスクも増えます。
</dd>

<dt>nruns</dt>
<dd>
<strong>[オプション]</strong>
帯域幅のテストを実行する回数。初期値は5回です。初回のテストは常に残りのテストを続行するためにベストな計算をするための試験的なものです。この回数が増えるとテストの精度も向上していきますが、増やした分、テストがタイムアウトするリスクも増えます。これは実行毎に約2秒から4秒かかるため、この値は <code>timeout</code> の値よりも超えるように考慮しなければなりません。
</dd>

</dl>


<h2 id="methods">メソッド</h2>

<dl class="api">

<dt>init(oConfig)</dt>
<dd>
<p>
帯域幅プラグインを設定するために <a href="BOOMR.html#init">BOOMR.init()</a> メソッドによって呼び出されます。
</p>
<h3>パラメーター</h3>
<dl>
<dt>oConfig</dt>
<dd><code>BOOMR.init()</code> を通して渡された設定オブジェクト。詳しくは <a href="#config">設定項目の説明</a> をご覧ください。
</dl>
<h3>返り値</h3>
<p>
<code>BOOMR.plugins.BW</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>run()</dt>
<dd>
<p>
帯域幅テストを開始します。
このメソッドは <a href="BOOMR.html#page_ready">page_ready</a> イベントが発生したときに自動的に呼び出されます。もし必要であれば自分で呼び出してもかまいません。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR.plugins.BW</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>abort()</dt>
<dd>
<p>
すぐに帯域幅のテストを中断して、すでに収集した値から帯域幅と遅延を計算します。このメソッドは帯域幅のテストが中断されると自動的に呼び出されます。<a href="BOOMR.html#init">BOOMR.init()</a> メソッドを呼び出すときに適切な <code>timeout</code> 値を設定することを推奨します。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR.plugins.BW</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>is_complete()</dt>
<dd>
<p>
帯域幅プラグインが終了したのかどうかを確認するために <a href="BOOMR.html#sendBeacon">BOOMR.sendBeacon()</a> によって呼び出されます。
</p>
<h3>返り値</h3>
<ul>
<li>プラグインが終了している場合は <code>true</code> を返します。</li>
<li>プラグインが終了していない場合は <code>false</code> を返します。</li>
</ul>
</dd>

</dl>

<h2 id="beacon">ビーコンパラメーター</h2>
<p>
このプラグインはビーコンに次のパラメーターを追加します:
</p>
<dl>
<dt>bw</dt> <dd>秒間のバイト数にしたユーザーの測定された帯域幅</dd>
<dt>bw_err</dt> <dd>測定したユーザーの帯域幅でエラーを除いた95%信頼できる値</dd>
<dt>lat</dt> <dd>ミリ秒にしたユーザーの HTTP 遅延</dd>
<dt>lat_err</dt> <dd>測定したユーザーの HTTP 遅延でエラーを除いた95%信頼できる値</dd>
<dt>bw_time</dt> <dd>帯域幅と遅延を測定したときのユーザーのブラウザーのタイムスタンプ</dd>
</dl>


<p class="perma-link">
最新のソースコードとドキュメントは <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a> に公開されています。
</p>

</body>
</html>
<!--
    Copyright (c) 2011, Yahoo! Inc.  All rights reserved.
    Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
-->
